<!DOCTYPE html>
<html>
    <head>

        <link rel="canonical" href="http://www.jointjs.com/" />
        <meta name="description" content="Create interactive diagrams in JavaScript easily. JointJS plugins for ERD, Org chart, FSA, UML, PN, DEVS, LDM diagrams are ready to use." />
        <meta name="keywords" content="JointJS, JavaScript, diagrams, diagramming library, UML, charts" />

        <link href="http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700" rel="stylesheet" type="text/css" />
        <link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet">

        <link rel="stylesheet" href="css/tutorial.css" />
        <link rel="stylesheet" href="../node_modules/prismjs/themes/prism.css">

        <!-- Dependencies: -->
        <script src="../node_modules/jquery/dist/jquery.js"></script>
        <script src="../node_modules/lodash/lodash.js"></script>
        <script src="../node_modules/backbone/backbone.js"></script>

        <link rel="stylesheet" type="text/css" href="../build/joint.min.css" />
        <script type="text/javascript" src="../build/joint.min.js"></script>

        <title>JointJS - JavaScript diagramming library - Getting started.</title>

    </head>
    <body class="language-javascript tutorial-page">

        <script>
            SVGElement.prototype.getTransformToElement = SVGElement.prototype.getTransformToElement || function(toElement) {
                return toElement.getScreenCTM().inverse().multiply(this.getScreenCTM());
            };
        </script>

        <div class="tutorial">

            <h2>Serialization</h2>

            <p>This is the third article of the intermediate section of the JointJS tutorial.
                <a href="events.html">Go back to events.</a>
                Alternatively, you can <a href="intermediate.html">return to index</a> of all articles.</p>

            <p>Data serialization is very easy in JointJS.
                It is done through two import/export functions on the Graph class:</p>

            <ul>
                <li><a href="/docs/jointjs#dia.Graph.prototype.toJSON" target="_blank"><code>graph.toJSON()</code></a> -
                converts the whole graph into a JSON object.</li>
                <li><a href="/docs/jointjs#dia.Graph.prototype.fromJSON" target="_blank"><code>graph.fromJSON()</code></a>
                - overwrite current graph contents with converted contents of a provided JSON object.</li>
            </ul>

            <h3 id="persistence">Persistence</h3>

            <p>The functions preserve all cells that have been added to the graph.
                Additionally, note that custom properties saved on the graph are preserved as well.
                You can use this to store additional state information:</p>

            <pre><code>var graph1 = new joint.dia.Graph();
graph1.set('graphCustomProperty', true);
graph1.set('graphExportTime', Date.now());
var jsonObject = graph1.toJSON();

// transmission of `jsonObject` across network etc.

var graph2 = new joint.dia.Graph(); // new empty graph
graph2.fromJSON(jsonObject);
graph2.get('graphCustomProperty'); // true
graph2.get('graphExportTime'); // e.g. 627247800000</code></pre>

            <p>It is important to remember that the two functions work with JSON objects - not JSON strings.
                However, if necessary, you can easily convert back and forth using the native JavaScript
                <code>JSON.stringify()</code> and <code>JSON.parse()</code> functions:</p>

            <pre><code>var graph1 = new joint.dia.Graph();
var jsonObject = graph1.toJSON();
var jsonString = JSON.stringify(jsonObject);

// transmission of `jsonString` across network etc.

var graph2 = new joint.dia.Graph(); // new empty graph
graph2.fromJSON(JSON.parse(jsonString));</code></pre>

            <p>Depending on how you store/transmit your app data, you may work with the JSON objects directly (e.g. when
                storing it in a non-relational database like MongoDB), or in the stringified form (which can be stored
                anywhere plaintext can be stored, at the added cost of stringifying &amp; parsing of the JSON object for
                every transmission).</p>

            <h3 id="synthetic-graphs">Synthetic Graphs</h3>

            <p>It is of course also possible to avoid using the <code>graph.toJSON()</code> function altogether and
                instead construct your own synthetic graphs; you just need to make sure that the object you provide is
                valid JSON and that it contains a <code>cells</code> array property:</p>

            <pre><code>var graph = new joint.dia.Graph();
graph.fromJSON({
    cells: [{
        id: 1,
        type: 'standard.Rectangle',
        position: {
            x: 100,
            y: 100
        },
        size: {
            width: 100,
            height: 100
        }
    }]
});</code></pre>

            <p>The <code>cells</code> array can even be empty, if you want to create an empty synthetic graph:</p>

            <pre><code>var graph = new joint.dia.Graph();
graph.fromJSON({ cells: [] });</code></pre>

            <h3 id="limitations">Limitations</h3>

            <p>Keep in mind the general limitations of the JSON format.
                Some commonly used native JavaScript data types (including <code>Function</code>, <code>Date</code>, and
                <code>undefined</code>) <a href="https://en.wikipedia.org/wiki/JSON#Unsupported_native_data_types">are
                not supported</a>.
                The variables that have values of these types will not be persisted.
                Among other things, this means that if persistence is important in your application, you should choose
                to define custom element/link subtypes instead of embedding custom functions into default
                <code>joint.dia.Element</code> and <code>joint.dia.Link</code> types.</p>

            <p>Additionally, if you want to make use of the JSON objects and directly store them into MongoDB, you
                should remember its additional restriction on object keys starting with the <code>.</code> (dot) or
                <code>$</code> (dollar sign) symbols.
                Those are reserved for internal use of the MongoDB system.
                This is significant in the context of JointJS because it precludes the use of CSS-style selectors in the
                <code>attrs</code> arrays of your Elements and Links.
                Therefore, if persistence is important to you and you want to save data directly to MongoDB, you should
                always define <a href="custom-elements.html#markup">custom subelement selectors in the markup of your
                custom elements</a> instead of relying on CSS-style selectors.</p>

            <p><a href="custom-elements.html">In the next section of the intermediate tutorial, we will learn about
                creating custom elements.</a></p>

        </div><!--end tutorial-->

        <script src="../node_modules/prismjs/prism.js"></script>
    </body>
</html>
